使用 OAuth v2 添加身份验证
OAuth v2 身份验证在界面上与大多数现代应用用户预期的登录流程相符。
用户通过 Zapier 进行身份验证的交互通常完全在应用自身的网站上完成，这有助于用户轻松连接账户，而无需共享账户凭证或查找 API 密钥。
用户会看到一个熟悉的窗口，来自您的应用，显示登录界面，或者如果他们已登录，则显示账户选择器，而无需输入凭证。一旦他们授权 Zapier 访问，应用将返回一个访问令牌，供 Zapier 在后续 API 调用中使用。
Zapier 在 Platform UI 中选择 OAuth v2 时，会实现“Authorization Code”授权类型。如果您的 OAuth v2 实现支持刷新令牌，您可以选择配置“Refresh Token”请求。
Platform UI 当前不支持其他授权类型。如果您的集成需要不同的 OAuth v2 授权类型，请改用 Zapier 支持的其他授权方式，例如 Session 或 API Key。
如果您的集成需要 OAuth v1 身份验证，请改用 Platform CLI 而非 Platform UI。
1. 配置 OAuth v2 组件
- 在 Zapier 视觉构建器的身份验证选项卡中，打开并选择 OAuth v2。
可选输入表单
-
大多数采用 OAuth v2 身份验证的应用都不需要输入表单。如果您的 API 在显示授权 URL 之前需要用户提供数据，或需要 URL 参数来生成授权 URL（如自托管应用的账户团队名称或站点 URL），或者您需要存储从服务器接收的字段以用于后续 API 调用，则需要添加输入表单。
-
通过选择“添加字段”并填写需要用户输入的字段详情，来添加这些额外字段。这将在重定向用户到授权 URL 之前，向用户显示一个包含这些字段的表单。
-
在构建 OAuth v2 输入表单 时，有两种字段类型可用。标准字段的工作方式类似于 Zapier 在触发器和操作中的其他输入表单。计算字段 确保您的应用的身份验证 API 调用响应返回特定字段。
-
对于由用户输入的标准字段，选择默认字段类型。首先添加最常用的字段，按照用户预期的顺序排列，因为添加后无法重新排序。填写以下选项：
– Key：该字段的内部名称，用于在 Zapier API 调用中引用。为方便起见，使用与您的 API 相同的键。请注意：client_id 和 client_secret 是保留字段，不能用作输入表单字段的键。
– Label：该字段的用户友好名称，将在身份验证表单中显示。
– Required? (复选框)：如果该字段是身份验证成功所必需的，请选中。
– Type：所有输入字段默认使用 string 文本类型；如果需要隐藏用户输入的数据，请选择 password。
– Help Text：提供详细信息以帮助用户完成身份验证，尤其是当他们不确定在哪里找到所需数据时。请使用 Markdown 格式化文本，并添加超链接如果必要。
– Input Format：(可选) 指导用户输入确切数据。例如，对于 子域，如 https://.yourdomain.com/。
– Default Value：设置该字段的默认值。对于可选字段，默认值将在初始连接创建时应用，并在 Zap 运行时替换缺失或空值。对于必填字段，此值仅在连接创建时使用，而在 Zap 运行时不会应用（Zapier 会针对缺失或空值引发错误）。
-
标记为密码的输入字段，以及所有包含敏感私有数据的身份验证字段（如 OAuth v2 中的用户名和密码），会在运行时自动屏蔽。这些值存储在 Auth bundle 中，用于 API 调用，但在 Zapier 的日志中会被替换为类似
:censored:6:82a3be9927:的屏蔽值。因此，无法在日志中查看确切的令牌或密钥。要验证令牌是否在后续 API 调用中使用相同的值，可以比较屏蔽值的字符，例如:censored:6:82a3be9927:在后续调用中会以相同的结尾如 9927。 -
每个输入字段会在您的身份验证设置中显示其标签、键、类型和必填状态。点击字段进行编辑，或点击齿轮图标并选择删除来移除字段。
- 对于计算字段（仅在 OAuth v2 和 Session Auth 中可用），请查看 计算字段文档。
OAuth 重定向 URL
- 打开您的应用的应用程序、集成或 API 设置，为与 Zapier 的 OAuth 集成添加一个新应用。从 Zapier Platform UI 的身份验证部分复制 OAuth 重定向 URL，并将其添加到您的应用集成设置中。
- 要在此 Zapier 集成中引用重定向 URL，请使用以下代码：
\{\{bundle.inputData.redirect_uri\}\}
添加 PKCE 支持
- Zapier 提供内置支持 PKCE（Proof Key for Code Exchange，简称“PKCE”），这是授权码流程的扩展，可增强安全防护。代码生成和交换步骤会在启用后由 Zapier 自动处理。
将应用凭据添加到 Zapier
- 在您的应用设置中，您会获得 Zapier 用于向您的应用验证身份的凭据——通常为 Client ID 和 Client Secret，尽管名称可能不同。从您的应用中复制这些凭据，然后在 Zapier OAuth 配置的第 3 步中，将其粘贴到相应字段。Zapier 会使用这些凭据以及授权 URL 来获取请求令牌。
-
点击“保存并继续”以保存进度。
-
Zapier 会自动在身份验证 API 调用中包含 Client ID 和 Secret，但如果您需要在集成的 API 调用或自定义代码中引用它们，请使用以下代码：– Client Secret:
\{\{process.env.CLIENT_SECRET\}\}– Client ID:\{\{process.env.CLIENT_ID\}\}
添加 OAuth 端点配置
- 添加您的应用的授权 URL，这是 Zapier 重定向用户进行身份验证的位置。从您的应用或集成设置中复制此 URL。
- 默认情况下，Zapier 会将客户端 ID、state、重定向 URI 以及标准的
code响应类型作为 URL 参数传递到授权 URL。如果需要自定义，请点击“显示选项”按钮并添加额外细节。
注意：Oauth2stateparam 是一个标准安全机制，用于确保授权请求仅来自您的服务器。大多数 Oauth 客户端支持此功能，并会返回 state 查询参数。Zapier Platform 会执行此检查，此字段为必需且无法禁用。state 参数由 Zapier 自动生成，并可通过 bundle.inputData.state 访问。由于 Zapier 使用 state 验证重定向 URL 的 GET 请求，因此它必须由 Zapier 生成以供后续验证。
-
要限制 Zapier 的访问范围，使其仅获取特定数据，请在“Scope”字段中添加 OAuth 作用域，使用逗号或空格分隔的列表。
-
添加您的应用的访问令牌请求 URL，通常为
POST类型调用，从 API 文档中获取。
-
默认情况下，Zapier 会将客户端 ID、客户端 Secret、授权码、重定向 URI 以及标准的
authorization_code授权类型作为请求正文传递。如果需要自定义，请点击“显示选项”按钮并添加额外细节。 -
如果您的 API 支持自动令牌刷新，请添加刷新令牌请求 URL，并选中“自动刷新令牌”选项。这将使用户的 Zap 在后台持续运行，通过自动刷新过期令牌避免中断。
-
如果访问令牌和刷新令牌请求未在响应顶层返回，请使用 Code Mode 修改响应，使令牌置于顶层。不支持存储响应中的嵌套对象。
-
Zapier 会自动在后续 API 请求中包含访问令牌，但如果需要手动引用，它存储在
authDatabundle 中，可使用\{\{bundle.authData.access_token\}\}或\{\{bundle.authData.accessToken\}\}，具体取决于您的 API 响应。
2. 添加测试 API 请求
- 添加一个不需要额外配置的 API 调用，通常为
/user或/me。输入 API URL，并设置调用类型，通常为GET。这用于测试用户凭证是否能成功调用您的应用。
- 默认情况下，访问令牌会随调用一起包含，就像后续所有 API 调用一样；如果您的 API 需要更多配置，请点击“显示选项”并添加必要参数。
- 要自定义测试 API 请求，请选择“切换到代码模式”并编写 JavaScript 代码处理调用和响应解析。首次切换时，Zapier 会将 API 调用转换为代码。切换回表单模式后，代码更改不会同步到表单，反之亦然。
3. 配置连接标签
查看 连接标签文档 以可选地区分用户连接的应用账户。
4. 测试您的身份验证
连接一个有效用户账户来测试身份验证。
视频教程
您还可以参考此视频，了解如何在 Zapier 集成中实现 OAuth v2：
需要帮助？告诉我们您的问题，我们会连接您到合适的资源或支持。